## -*- mode: html; coding: utf-8; -*-
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: Access Control Admin Internals -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking CDS Invenio</a> &gt; <a class="navtrail" href="webaccess-internals">WebAccess Internals</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->

<pre>
These are the functions called by the WebAccess Web Admin Interface to administrate
the wanted authorizations. This listing is of the most important functions.

For more information look in the source code or at the signatures.

CONTENTS
 1. Adding Information
 2. Finding Information
 3. Deleting Information

1. Adding Information

acc_add_action(name_action='', description='', optional='no', *allowedkeywords)
    function to create new entry in accACTION for an action

    name_action     - name of the new action, must be unique

      keyvalstr     - string with allowed keywords

    allowedkeywords - a list of allowedkeywords

    keyvalstr and allowedkeywordsdict can not be in use simultanously

    success -> return id_action, name_action, description and allowedkeywords
    failure -> return 0



acc_add_role(name_role, description, firerole_def_ser, firerole_def_src)
    add a new role to accROLE in the database.

       name_role - name of the role, must be unique

     description - text to describe the role

firerole_def_ser - precompiled serialized firewall like role definition (firerole)

firerole_def_src - definition text source for repairing after Python upgrades



acc_add_user_role(id_user=0, id_role=0, email='', name_role='')
     this function adds a new entry to table user_accROLE and returns it

      id_user, id_role - self explanatory

        email - email of the user

    name_role - name of the role, to be used instead of id.



acc_add_role_action_arguments_names(name_role='', name_action='', arglistid=-1, optional=0, verbose=0, **keyval)
     this function makes it possible to pass names when creating new entries instead of ids.
    get ids for all the names,
    create entries in accARGUMENT that does not exist,
    pass on to id based function.

    name_role, name_action - self explanatory

    arglistid - add entries to or create group with arglistid, default -1 create new.

     optional - create entry with optional keywords, **keyval is ignored, but should be empty

      verbose - used to print extra information

     **keyval - dictionary of keyword=value pairs, used to find ids.



2. Finding Information

acc_find_possible_actions(id_role, id_action)
    Role based function to find all action combinations for a
    give role and action.

      id_role - id of role in the database

    id_action - id of the action in the database

    returns a list with all the combinations.
    first row is used for header.



3. Deleting Information

acc_deletea_ction(id_action=0, name_action=0)
    delete action in accACTION according to id, or secondly name.
    entries in accROLE_accACTION_accARGUMENT will also be removed.

      id_action - id of action to be deleted, prefered variable

    name_action - this is used if id_action is not given

    if the name or id is wrong, the function does nothing



acc_delete_role(id_role=0, name_role=0)
     delete role entry in table accROLE and all references from other tables.

      id_role - id of role to be deleted, prefered variable

    name_role - this is used if id_role is not given



acc_delete_user_role(id_user, id_role=0, name_role=0)
     function deletes entry from user_accROLE and reports the success.

      id_user - user in database

      id_role - role in the database, prefered parameter

    name_role - can also delete role on background of role name.



acc_delete_role_action_arguments_names(name_role='', name_action='', arglistid=1, **keyval)
    utilize the function on ids by first finding all ids and redirecting the function call.
    break of and return 0 if any of the ids can't be found.

    name_role = name of the role

    name_action - name of the action

    arglistid - the argumentlistid, all keyword=value pairs must be in this same group.

    **keyval - dictionary of keyword=value pairs for the arguments.



</pre>
